gh-1145: Add an overview of Diátaxis to the style guide #1177

Jamesgo1 · 2023-10-06T11:22:42Z

Hello,

I've made an initial attempt at adding a Diataxis section to the style guide based on the issue here. Any feedback appreciated.

📚 Documentation preview 📚: https://cpython-devguide--1177.org.readthedocs.build/

erlend-aasland · 2023-10-06T11:27:05Z

cc. @evildmp

documentation/style-guide.rst

evildmp

This is an excellent start, with a few adjustments I think it can be published, and then we can look at further improvement.

evildmp · 2023-10-06T12:49:06Z

documentation/style-guide.rst

+Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_
+framework. This means adapting the writing style according to the nature of
+the documentation that is being written. The framework splits documentation
+into four distinct types: tutorials, how-to guides, reference, and


I think I'd prefer to say: "... identifies documentation of four distinct types: ..." (because although often or usually this means an architectural division too, it's not the most important thing).

evildmp · 2023-10-06T12:49:43Z

documentation/style-guide.rst

+into four distinct types: tutorials, how-to guides, reference, and
+explanation.
+
+`Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be


This ought to be a Sphinx reference, I guess using InterSphinx.

And as you mentioned below, it should be tutorial -- singular.

evildmp · 2023-10-06T13:00:22Z

documentation/style-guide.rst

+
+`Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be
+beginner-friendly, explicit, and avoid making assumptions about the reader's
+knowledge. The goal of a tutorial is to get the user writing Python code as


In fact there is a single Python tutorial - this end-to-end learning journey that has been conceived and implemented, and I think that's an important fact about it. I think I would like to say something like:

The goal of the tutorial is to provide a learning experience, in which a user is guided through a series of activities, and in doing so encounters concepts, actions tools and so on. The minimum possible explanation and technical detail should be provided (link to further information when required).

I'd actually say nothing about beginners - there could be in principle a very advanced tutorial.

Also possible to link to https://diataxis.fr/tutorials/ - also available via InterSphinx.

evildmp · 2023-10-06T13:17:35Z

documentation/style-guide.rst

+tutorials and how-to guides are instructional rather than explanatory
+and should provide clear, logical steps on how to complete a task. However,
+how-to guides make more assumptions about the user's knoweldge and place
+greater emphasis on the user finding the best way to complete the task.


I think good language for how-to guides is around "problems". E.g.: "A how-to guide talks the user through a problem-field." Sometimes it's a simple 1-2-3-4 series of operations, but more often it's more complex than that.

The key thing is that how-to guides are to help someone get their work done.

I would also use a more concrete language and focus on what they are first, and how they are similar and/or different from the tutorials afterwards.

evildmp · 2023-10-06T13:19:13Z

documentation/style-guide.rst

+greater emphasis on the user finding the best way to complete the task.
+
+`Python references <https://docs.python.org/3/library/index.html>`_ should
+be factual, concise, and clear. The purpose of reference documentation is


I don't think we need to say that anything should be concise or clear - that's probably a given for documentation.

evildmp · 2023-10-06T13:19:29Z

documentation/style-guide.rst

+:ref:`Code-examples` can be a useful way of achieving these
+objectives.
+
+`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide


explanation singular.

evildmp · 2023-10-06T13:23:57Z

documentation/style-guide.rst

+Diátaxis
+========
+
+Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_


I forgot to include this in my first review: this should definitely be something like: Python's documentation is moving towards an implementation of Diátaxis. It's not there yet by any means!

Maybe something like "strives to follow", so we don't need to update the text once we do get there?

ezio-melotti

Overall good -- the wording could be a bit more concise/concrete IMHO.

ezio-melotti · 2023-10-10T11:48:31Z

documentation/style-guide.rst

+Diátaxis
+========
+
+Python's documentation follows the `Diátaxis <https://diataxis.fr//>`_


Maybe something like "strives to follow", so we don't need to update the text once we do get there?

ezio-melotti · 2023-10-10T11:49:50Z

documentation/style-guide.rst

+into four distinct types: tutorials, how-to guides, reference, and
+explanation.
+
+`Python tutorials <https://docs.python.org/3/tutorial/index.html>`_ should be


And as you mentioned below, it should be tutorial -- singular.

ezio-melotti · 2023-10-10T11:51:51Z

documentation/style-guide.rst

+tutorials and how-to guides are instructional rather than explanatory
+and should provide clear, logical steps on how to complete a task. However,
+how-to guides make more assumptions about the user's knoweldge and place
+greater emphasis on the user finding the best way to complete the task.


I would also use a more concrete language and focus on what they are first, and how they are similar and/or different from the tutorials afterwards.

ezio-melotti · 2023-10-10T11:56:37Z

documentation/style-guide.rst

+:ref:`Code-examples` can be a useful way of achieving these
+objectives.
+
+`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide


I'm not sure the glossary is a good example of explanation, and we don't really have a section for those. Some documents (e.g. a good chunk of the Unicode HOWTO) could be classified as explanations, but they are currently hidden throughout the docs.

There's also a typo in the link (if you use intersphinx this suggestion won't be needed):

Suggested change

`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide

`Python explanations <https://docs.python.org/3/glossary.html>`_ provide

ezio-melotti · 2023-10-10T11:58:31Z

documentation/style-guide.rst

+
+`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide
+a deeper level of understanding and are naturally more discursive. They aim
+to deepen the reader's understanding and answer 'why' questions. They should


I think this should use double quotes:

Suggested change

to deepen the reader's understanding and answer 'why' questions. They should

to deepen the reader's understanding and answer "why" questions. They should

willingc · 2023-10-10T15:29:50Z

@Jamesgo1 Thanks for submitting your first PR to the devguide. If you can fix these few review suggestions, we can rereview and merge since this is a helpful addition. 🌻

Jamesgo1 · 2023-11-15T22:11:11Z

Thanks so much for the feedback! Just messaging to say I'm still working on this but I've just been really busy these last couple of weeks. I should hopefully have more time now.

willingc · 2023-11-15T22:27:29Z

Thanks for checking in @Jamesgo1. No stress. We all have things going on. Very grateful that you are working on this and it is off to a great start.

…ping in conf.py

Jamesgo1 · 2023-12-22T00:32:42Z

Sorry for the delay on this!

Thanks a lot for your feedback @ezio-melotti and @evildmp. All your suggestions make sense and I've tried to implement them as best as I can. I've changed the references to inter-sphinx (thanks for your help @AA-Turner). The how-to index doesn't seem to have a reference in the cpython docs so that's the only one I didn't change.

I've tried to make the wording more concise/less verbose based on your feedback @ezio-melotti

Of course, happy to refine again based on any other feedback.

willingc

Thanks @Jamesgo1 for looping back to this PR. I started the CI and the content looks good to me.

documentation/style-guide.rst

…x link for tutorials.

willingc · 2024-02-06T21:06:20Z

Thanks @Jamesgo1 for your patience on this. Thanks @ambv for merging.

Add Diataxis section to style-guide.rst

89e2af5

hugovk reviewed Oct 6, 2023

View reviewed changes

documentation/style-guide.rst Outdated Show resolved Hide resolved

documentation/style-guide.rst Outdated Show resolved Hide resolved

evildmp suggested changes Oct 6, 2023

View reviewed changes

evildmp reviewed Oct 6, 2023

View reviewed changes

AA-Turner changed the title ~~gh-1145: Added Diataxis section to style-guide.rst~~ gh-1145: Add an overview of Diátaxis to the style guide Oct 6, 2023

ezio-melotti reviewed Oct 10, 2023

View reviewed changes

willingc added the needs: PR update An update or rebase to an existing PR is needed. label Oct 10, 2023

Jamesgo1 added 2 commits December 21, 2023 23:56

Implemented changes from review and added Diataxis to intersphinx map…

777e0c2

…ping in conf.py

Implement Diataxis changes suggested by ezio-melotti

284e345

willingc removed the needs: PR update An update or rebase to an existing PR is needed. label Dec 22, 2023

willingc approved these changes Dec 22, 2023

View reviewed changes

hugovk reviewed Dec 22, 2023

View reviewed changes

documentation/style-guide.rst Outdated Show resolved Hide resolved

Link directly to Diataxis for home page references and add intersphin…

e04805e

…x link for tutorials.

erlend-aasland approved these changes Jan 4, 2024

View reviewed changes

ambv merged commit 1a56667 into python:main Feb 6, 2024
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-1145: Add an overview of Diátaxis to the style guide #1177

gh-1145: Add an overview of Diátaxis to the style guide #1177

Jamesgo1 commented Oct 6, 2023 •

edited by hugovk

Loading

erlend-aasland commented Oct 6, 2023

evildmp left a comment

evildmp Oct 6, 2023

evildmp Oct 6, 2023

ezio-melotti Oct 10, 2023

evildmp Oct 6, 2023

evildmp Oct 6, 2023

evildmp Oct 6, 2023

ezio-melotti Oct 10, 2023

evildmp Oct 6, 2023

evildmp Oct 6, 2023

evildmp Oct 6, 2023

ezio-melotti Oct 10, 2023

ezio-melotti left a comment

ezio-melotti Oct 10, 2023

ezio-melotti Oct 10, 2023

ezio-melotti Oct 10, 2023

ezio-melotti Oct 10, 2023

ezio-melotti Oct 10, 2023

willingc commented Oct 10, 2023

Jamesgo1 commented Nov 15, 2023

willingc commented Nov 15, 2023

Jamesgo1 commented Dec 22, 2023

willingc left a comment

willingc commented Feb 6, 2024

	`Python explanations <https://docs.python.org/3/glossary.htmll>`_ provide
	`Python explanations <https://docs.python.org/3/glossary.html>`_ provide

	to deepen the reader's understanding and answer 'why' questions. They should
	to deepen the reader's understanding and answer "why" questions. They should

gh-1145: Add an overview of Diátaxis to the style guide #1177

gh-1145: Add an overview of Diátaxis to the style guide #1177

Conversation

Jamesgo1 commented Oct 6, 2023 • edited by hugovk Loading

erlend-aasland commented Oct 6, 2023

evildmp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ezio-melotti left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willingc commented Oct 10, 2023

Jamesgo1 commented Nov 15, 2023

willingc commented Nov 15, 2023

Jamesgo1 commented Dec 22, 2023

willingc left a comment

Choose a reason for hiding this comment

willingc commented Feb 6, 2024

Jamesgo1 commented Oct 6, 2023 •

edited by hugovk

Loading